docs: node scan rfc by alegrey91 · Pull Request #922 · kubewarden/sbomscanner

alegrey91 · 2026-03-10T10:17:06Z

Description

Node Scan feature RFC.
Fix #889

Test

To test this pull request, you can run the following commands:

Additional Information

Tradeoff

Potential improvement

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

Copilot

Pull request overview

Adds an RFC describing the proposed “Node Scan” feature, outlining how node scanning should work and integrate with SBOMscanner, including intended CRDs and status conditions.

Changes:

Introduces a new RFC document for Node Scanning.
Describes the DaemonSet-based architecture and reuse of the worker via scan mode flagging.
Proposes new CRDs, a NodeMetadata structure, and NodeScanJob status conditions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

codecov · 2026-03-10T10:48:13Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.22%. Comparing base (3a8bcd2) to head (f2fc011).
⚠️ Report is 267 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #922      +/-   ##
==========================================
+ Coverage   49.95%   52.22%   +2.26%     
==========================================
  Files          56       61       +5     
  Lines        4544     5147     +603     
==========================================
+ Hits         2270     2688     +418     
- Misses       1928     2071     +143     
- Partials      346      388      +42

Flag	Coverage Δ
unit-tests	`52.22% <ø> (+2.26%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Flavio Castelli <flavio@castelli.me>

flavio

This is a good start. There are details that are not covered, such as:

The daemonset will stay idle most of the time
How is the scan initiated
How is the SBOM performed. We both know this is going to be based on trivy scanning the filesystem of the host, mounted into the container. Explain that. Also, we will probably need to provide a way to exclude some host directories from the scan. AFAIK there's the risk of trivy scanning the directories where the container root filesystem is splatted, leading to assigning CVEs of the container images to the host itself.
Alternative approach: we could find creative way to spin up and down the daemonsets on demand. But this something that requires more work compared to the initial proposal. We expect the agent to be idle most of the time, consuming very little resources. We can revisit the approach later on, when we have real data.

Co-authored-by: Flavio Castelli <flavio@castelli.me> Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 · 2026-03-12T12:58:04Z

Also, we will probably need to provide a way to exclude some host directories from the scan. AFAIK there's the risk of trivy scanning the directories where the container root filesystem is splatted, leading to assigning CVEs of the container images to the host itself.

You are right. The field skip in the NodeScanConfiguration does exactly this thing.

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

fabriziosestito · 2026-04-15T12:40:22Z

+
+## Garbage Collection
+
+Garbage collection is crucial to prevent resource orphaning and to maintain a clean cluster state. 


There are two distinct cleanup mechanisms to consider: the GC and the configuration cleanup.

Kubernetes garbage collection (Node deletion)

The owner reference chain is: Node → NodeScanJob, and Node → NodeSBOM → NodeVulnerabilityReport. When a Node is deleted, Kubernetes garbage collection cascades through the owner references and cleans up all node-related resources automatically.

Reconciler cleanup (NodeScanConfiguration disabled/deleted)

When the NodeScanConfiguration is disabled or removed, the reconciler must actively clean up NodeScanJobs and NodeSBOMs. NodeVulnerabilityReports are cascade-deleted for free since they are owned by their respective NodeSBOM.

fabriziosestito · 2026-04-15T12:43:52Z

+    If not specified, all the nodes are scanned.
+  * `skip`: A list of file/directory paths to be ignored.
+
+* `NodeScanJob`: Represents a single execution of a node scan.


Let's reuse the same retention mechanism used for ScanJobs: keep only the latest 10 NodeScanJobs per node.
See:

sbomscanner/docs/rfc/0002_scan_trigger.md

Line 314 in e5d13da

## ScanJob retention

fabriziosestito · 2026-04-15T12:49:40Z

+
+* `Name` specifies the unique name of the node in the cluster.
+* `Platform` specifies the OS + CPU architecture of the node. Example: linux/amd64, linux/arm64.
+


Please add a section describing which reconcilers need to be introduced, along with a couple of paragraphs explaining their role in the design.

NodeScanJobReconciler

NodeScanReconciler

NodeScanRunner (as a runnable)

The NodeScanRunner filters nodes using the nodeSelector and platform criteria. The platform filter can be implemented using controller-runtime indexes.

fabriziosestito · 2026-04-15T12:49:57Z

+
+## CRDs
+
+For this feature we are going to add the following CRDs:


please add example CRDs

fabriziosestito · 2026-04-15T12:51:11Z

+* `NodeScanConfiguration`: Defines the global scan settings.
+  * `scanInterval`: Duration between automated scans.
+    If not specified, the `NodeScanJob` doesn't start.
+  * `nodeSelector`: Filter which nodes are scanned.


add platform(s) filter

fabriziosestito · 2026-04-15T13:01:39Z

+    If not specified, the `NodeScanJob` doesn't start.
+  * `nodeSelector`: Filter which nodes are scanned.
+    If not specified, all the nodes are scanned.
+  * `skip`: A list of file/directory paths to be ignored.


We could use something like this for skip patterns:

# Gitignore-style patterns to exclude from filesystem scans. # Trailing "/" = directory, otherwise = file. skipPatterns: - "node_modules/" # → --skip-dirs node_modules - "**/vendor/" # → --skip-dirs (glob expanded at scan time) - ".git/" # → --skip-dirs .git - "*.min.js" # → --skip-files *.min.js - "package-lock.json" # → --skip-files package-lock.json

fabriziosestito · 2026-04-15T13:03:51Z

+
+## Scan Workflow
+
+1. The user applies a `NodeScanConfiguration` with a defined `scanInterval` or applies a `NodeScanJob` manually.


Let's revisit this and add the runner. That way we have two branches in the flow: one triggered by the user, and one triggered by the runner.

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 added 3 commits March 5, 2026 18:27

docs(rfc): add node scanning

886c479

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

update rfc

e2e83f8

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

reviewed document

634fb5a

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 requested a review from a team as a code owner March 10, 2026 10:17

Copilot AI review requested due to automatic review settings March 10, 2026 10:17

github-project-automation Bot added this to SBOMscanner Mar 10, 2026

github-project-automation Bot moved this to Pending Review in SBOMscanner Mar 10, 2026

Copilot started reviewing on behalf of alegrey91 March 10, 2026 10:17 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

Comment thread docs/rfc/0008_node_scan.md Outdated

Comment thread docs/rfc/0008_node_scan.md

Comment thread docs/rfc/0008_node_scan.md Outdated

Apply suggestions from code review

5d7a867

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Flavio Castelli <flavio@castelli.me>

flavio requested changes Mar 12, 2026

View reviewed changes

Comment thread docs/rfc/0008_node_scan.md

Comment thread docs/rfc/0008_node_scan.md Outdated

Comment thread docs/rfc/0008_node_scan.md

Comment thread docs/rfc/0008_node_scan.md Outdated

Update docs/rfc/0008_node_scan.md

64635ff

Co-authored-by: Flavio Castelli <flavio@castelli.me> Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 added 2 commits March 12, 2026 16:11

fix doc

37c0bcb

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

add design details

798bd9f

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

flavio removed this from SBOMscanner Mar 13, 2026

alegrey91 commented Apr 2, 2026

View reviewed changes

Comment thread docs/rfc/0008_node_scan.md Outdated

alegrey91 commented Apr 2, 2026

View reviewed changes

Comment thread docs/rfc/0008_node_scan.md

add images and improve rfc

cde44ed

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 changed the title ~~docs: node scanning rfc~~ docs: node scan rfc Apr 3, 2026

github-project-automation Bot added this to SBOMscanner Apr 3, 2026

github-project-automation Bot moved this to Pending Review in SBOMscanner Apr 3, 2026

alegrey91 added 2 commits April 3, 2026 12:01

update doc

60da031

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

nodescanconfig as singleton

d1db95f

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

alegrey91 requested review from fabriziosestito and flavio April 3, 2026 12:14

alegrey91 added 2 commits April 9, 2026 11:53

add garbace collection section

4a9ce79

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

update resource image with updated names

402020e

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

fabriziosestito requested changes Apr 15, 2026

View reviewed changes

add gc image

f2fc011

Signed-off-by: Alessio Greggi <alessio.greggi@suse.com>

fabriziosestito assigned alegrey91 Apr 16, 2026

fabriziosestito added the documentation Improvements or additions to documentation label Apr 16, 2026


		## Garbage Collection

		Garbage collection is crucial to prevent resource orphaning and to maintain a clean cluster state.


		* `Name` specifies the unique name of the node in the cluster.
		* `Platform` specifies the OS + CPU architecture of the node. Example: linux/amd64, linux/arm64.


		## CRDs

		For this feature we are going to add the following CRDs:


		## Scan Workflow

		1. The user applies a `NodeScanConfiguration` with a defined `scanInterval` or applies a `NodeScanJob` manually.

Conversation

alegrey91 commented Mar 10, 2026

Description

Test

Additional Information

Tradeoff

Potential improvement

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

flavio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alegrey91 commented Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

fabriziosestito Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov Bot commented Mar 10, 2026 •

edited

Loading